pp108 : Configuring JMS Connector

Configuring JMS Connector

This topic describes the procedure to configure JMS connector.

Functional architecture

JMS connector is an integral part of Process Platform and is shipped with other connector stacks. It supports distribution transactions and message persistence functionality. JMS connector can be used with other brokers as well, but version 3.0 is being shipped with Apache ActiveMQ support.

The following are the key features of JMS connector:

  • JMS connector follows the pull and push mechanism to read the messages from the Queue or Topic.
  • The Interval poller reads messages based on a preset time interval following the pull mechanism. On message arrival, the broker pushes the message to the connector and triggers the Compatibility poller.
  • The Request-Reply poller is an extension of the Compatibility poller. The poller performs additional job to server request-reply scenario with Process Platform. 
Poller types Description
Compatibility When the poller is started, it opens a transacted session to the JMS provider and registers a consumer. Each message that arrives is immediately picked up, and after processing each message, the session is either committed or rolled back.
Interval At each specified period of time, the connector checks the queue to see if there are any messages to be processed.
Custom You can extend one of the default pollers or write your own poller.
Request-Reply The specialized poller handles the request-reply scenarios from Process Platform.

JMS connector configuration

Before you begin this task

  • Ensure that Java 8 is installed.
  • You must have the JMS Administrator role to configure JMS.
  • Configure JMS and ActiveMQ for Reliable Messaging
    Note: ActiveMQ must be configured based on the environment requirement, that is, memory setup, policy configuration, and so on. The configuration changes must be done on <ActiveMQ Root>/conf/activemq.xml.

GUI configuration

JMS connector configuration is divided in to three parts.

  • General
  • Triggers
  • Destination Managers

The configuration elements follow the relationship as shown in the following diagram:

To configure JMS connector:

  1. Go to CUSP > JMS Connector Configuration. The JMS Connector Configuration page is displayed.
  2. Create a configuration or modify an existing configuration.

The JMS Connector Configuration page has the following tabs:

General tab 
Field name Description  Mandatory  Accepted input values
JMS Polling Interval Polling interval to poll messages from the destination N

If not specified, the default value is configured to 10 seconds.

Note: This value is not used when the poller type is Compatibility. Only the Interval Poller uses this configuration. The values entered must be in milliseconds.

Charset Character set that must be used N When not specified, the default value is UTF-8.
Timeout

Timeout to use when sending SOAP messages to the bus

N  

Is BTC Enabled

Specifies whether BTC is enabled N The default value is false.
Run With Config Error

Specifies whether the connector must start up if there are configuration errors

N The default value is false.
Check Connection On Request Specifies whether the connections must be checked for every request N The default value is false.
Disable Message Selectors

Specifies whether the message selectors must be disabled even if the JMS type supports it

N

The default value is false.

Note: When set to true, the connector internally maintains the status of the message processing.

Triggers tab 
Field name Description  Mandatory Accepted input values 
Trigger      
Name Logical name for the trigger to be entered for the InboundMessageTrigger in the destination configurations  Y  
Operation Name of the operation to call when the trigger is fired  Y In case of triggering a business process, ExecuteProcess is the operation name.
Namespace Namespace of the operation to use when the trigger is fired Y For example: ExecuteProcess in BPM, "http://schemas.cordys.com/bpm/execution/1.0"
User DN

DN of the user using which the messages are sent

Note: All the messages on the queue are sent using this account.

 Y For example: cn=userId,cn=organizational users,o=system,cn=cordys,cn=CORDYS_JMS,o=opentext.net
Organization DN DN of the organization in which the message is sent  Y For example: o=system,cn=cordys,cn=CORDYS_JMS,o=opentext.net
Charset Charset to use for the trigger N The default value is UTF8.
Request Timeout

Timeout to use when sending the message to the bus.

Note: If the message is sent in a non-reliable mode, the system uses a socket to connect to the bus.

N  
Send Reliably Decides the mode of communication with Process Platform N The default value is set to true. If Send Reliably is set to true, the JMS connector uses the JMS connection point. Otherwise, it uses the socket connection point for the target service container, BPM.
Parameters

Parameter XML for the trigger where you can specify nodes and attributes to contain variables that are replaced with information received from the message.

 

Y

The following variables are available, which apply to attributes and nodes too if no limitation is provided:

    • inputmessage - The message body appears exactly as it is in the message. It is only available for nodes.

Note: This can produce errors if this is binary. Use inputmessagebase64 instead.

    • inputmessagebase64 - This is similar to inputmessage with the difference that the message body is base64 encoded. It is only available for nodes.
    • xmlmessage - The message body converted to XML using the Binary Transformation configuration (if that one was not configured, this will be empty). It is only available for nodes.
    • messageprotocol - Binary transformation protocol used to convert the message.
    • messageid - Message ID from the message.
    • correlationid - Correlation ID from the message.
    • fromdestination - Name of the destination from where the message came.
    • reply2destination - Name of the destination to reply to
    • jmstype - JMS type from the message.
    • properties - Properties found in the message. It is only available for nodes. Each property has a child node (named ‘property’) with a name attribute containing the name of the property and a type attribute containing the type of the property value. The value of the node is the property value, for example, <propery name=�?Prop�? type=�?String�?>value</property>.

The following are the sample parameters for ExecuteProcess:

        <type>definition</type>
        <receiver>com-cordys-coe/jmsconnector/bpm/DemoTrigger</receiver>
        <source>Triggered via JMS</source>
        <message>
          <DemoTrigger_IP xmlns="http://schemas.cordys.com/default">
            <inputmessageinxml>{$inputmessageinxml}</inputmessageinxml>
            <inputmessage>{$inputmessage}</inputmessage>
            <fromdestination>{$fromdestination}</fromdestination>
            <correlationid>{$correlationid}</correlationid>
            <inputmessagebase64>{$inputmessagebase64}</inputmessagebase64>
            <xmlmessage>{$xmlmessage}</xmlmessage>
            <reply2destination>{$reply2destination}</reply2destination>
            <jmstype>{$jmstype}</jmstype>
            <messageprotocol>{$messageprotocol}</messageprotocol>
            <messageid>{$messageid}</messageid>
            <properties>{$properties}</properties>
          </DemoTrigger_IP>
        </message>

Custom Trigger Processor      
Class Name Fully qualified class name of the trigger N For example: com.test.custom.SampleCustomTrigger
Input Parameters Input parameter passed to the custom trigger processor class N  
Destination Managers tab 
Field name Description  Mandatory Accepted input values 
Destination Manager      
Name Logical name of the destination manager. This is the name used in the SOAP API to identify the manager. Therefore, when you want to send a message to this destination, you must use destinationmanager.destination. Y  
JMS Vendor

Classname of the InitialContextFactory to use.

Y For ActiveMQ, you must use org.apache.activemq.jndi.ActiveMQInitialContextFactory.
Provider URL Value to use for the java.naming.provider.url parameter in the JMS context properties. Y Broker URL, for example, tcp://localhost:61616. The default is set to tcp://localhost:61616. This needs to change as per the environment.
Username User name for connecting to the specific destination manager. N If security is set to broker, the username is mandatory.
Password

Password for connecting to the specific destination manager.

N If security is set to broker, the password is mandatory.
Connection Factory Name Name of the connection factory referred by the destination. Y Logical name referred by the destination.
Connection User

Username to use if the JNDI connection needs a username.

N If security is set for the broker connection factory, the username is mandatory.
Connection Password Password to use if the JNDI connection needs a username. N If security is set for the broker connection factory, the password is mandatory.
Authentication Type

Authentication type to use.

N

Must be none when no authentication is required.

Set it to Basic when a username/password is required to connect to the destination manager.

Charset

Character set to use for the destination manager.

N The default value is UTF8.
Timeout Timeout to use when sending and receiving messages for the destination manager.   The default destination manager timeout is 20 seconds.
Shutdown Destination Specific queue to stop listening to the messages where the system creates an inactive listener. N  
Destinations      
Name Logical name for the destination. Y To identify a queue in the SOAP API, use the logical names. For example, if the destination manager is called activemq and the destination is called CordysToOutside, then use activemq.CordysToOutside to identify the queue.
Access Access type of the queue through which you can ensure only messages are read from the destination. Y

The possible values are:

  • Read
  • Write
  • Both  (Default)
Username Queue-specific username to use. N  
Password Queue-specific password to use. N  
Charset Charset to use. When not specified, the charset of the destination manager is used. N The default value is UTF8.
Inbound Message Trigger

Name of the trigger to execute when a message is picked up.

N  
Authentication Type

Authentication type to use.

N

When set to none, no authentication is required.

Set it to basic if the destination requires a different username and password.

Destination Physical Name Physical details of the destination. Y Actual name of the Queue or Topic defined on the broker.
Type Destination type Y

The possible values are:

  • Queue
  • Topic
Message Selector Custom selector to use for filtering the messages that are monitored. N

The sample values are:

  • JMSMessageID='<JMS MessageId>'
  • JMSCorrelationID='<JMS Message CorrelationId>' 
Dynamic Destination Parameters Parameters in case this is a dynamic destination. N  
Error Destination

Name of the destination to which messages must be copied when processing fails.

N This must be the actual error queue name, for example, destinationManager.Queue.
Number of Trigger Listeners Number of threads that must be used for handling messages that are received from the queue. N

If MaintainSequence is set to true, then this must always be set to 1.

This is the number of listeners created on the destination.

Is Dynamic Indicates whether this destination is dynamic. N The default value is false.
Is Durable Subscriber Indicates whether this destination is a durable subscriber. N The default value is false.
Is Default Error Destination Indicates whether this destination is used as the default error queue if processing fails. N The default value is false.
Poller      
Type

Type of poller to use.

Y

The possible values are:

  • Compatibility (Default)
  • Interval_Polling
  • Custom
  • Request_Reply_Compatibility

Note: For each poller type, the options displayed are listed below.

Compatibility      
Ignore Redelivery Count The poller processes the message irrespective of the message redelivery count, if set to true. N The default value must be set to true.
Interval Poller      
Problem Check Interval Indicates the interval to be used to solve the problem by trying to process the message again in seconds N

The default value is 300, which means 5 minutes.

The expected value is in seconds.

Max Retry Count

Number of times the problem solver tries to resend the message.

Note: If after this time the message is not sent, the queue is blocked until an administrator unblocks the queue.

N The default value is 3.
Polling Interval Polling interval to use for polling. If not specified, then the generically configured polling interval is used. N

The default value is 10 seconds.

Expected value is in minutes.

Maintain Sequence Indicates whether the sequence of the messages must be maintained. N When set to true, if the current message fails to process, this poller is blocked until the problem is resolved.
Raise Problem When Blocked Indicates whether or not the a problem must be raised in the problem registry when this poller is blocked.    
Custom      
Class Name Name of the class. Y  
Input Parameters Parameters for the custom class. N  
Request_Reply_Compatibility      
Ignore Redelivery Count If set to true, the poller processes the message irrespective of the message redelivery count. N The default value must be set to true.

Service container configuration

Along with the GUI configuration, the service container must also be configured for JMS configuration.

To configure JMS service container:

  1. Go to CUSP > System Resource Manager. The System Resource Manager page is displayed with the available service containers.
  2. Select  OpenText JMS Connector, and then right-click Properties. The JMS properties page is displayed.
  3. Click the JRE Configuration tab, and then perform the following configurations:
      1. In Classpath, add the Atomikos and ActiveMQ related jars, for example, <folder location>\atomikos-util.jar;<folder location>\transactions.jar;<folder location>\transactions-api.jar;<folder location>\transactions-jta-3.8.0.jar;<folder location>\activemq-all-5.6.0.jar.
      2. In the JVM Property section, add:
        • -Dcom.cordys.xatransaction.TransactionManagerFactory=com.cordys.xatransaction.atomikos.AtomikosTransactionManagerFactory
        • -Dcom.cordys.transport.jms.jndifile=<Installation Directory>configreliableMessaging.properties
      3. Click the OpenText JMS Connector tab, and then select the configuration to be attached to the service container.  
    Note: The configuration values in the drop down list are available after setting up the JMS connector through the CUSP task.
  4. Save and restart the configuration.

Note: See Using JMS Connector to verify the JMS configuration.

Attachments: